Dec29, 2025

Como integrar o Helium com o CapSolver para resolução de CAPTCHA sem interrupções

Adélia Cruz

Neural Network Developer

1. Introdução

A automação da web requer ferramentas que sejam poderosas e fáceis de usar. No entanto, os sites modernos implementam medidas anti-bot e CAPTCHAs sofisticados que podem interromper os scripts de automação.

A combinação do Helium e do CapSolver oferece uma solução elegante:

Helium: Uma biblioteca Python leve que torna o Selenium mais fácil de usar com uma API de leitura intuitiva
CapSolver: Um serviço de resolução de CAPTCHA baseado em IA que lida com Cloudflare Turnstile, reCAPTCHA e mais

Juntos, essas ferramentas permitem automação da web sem interrupções, resolvendo desafios de CAPTCHA automaticamente.

1.1. Objetivos da Integração

Este guia o ajudará a atingir três objetivos principais:

Simplificar a automação do navegador - Use a API intuitiva do Helium para código limpo e legível
Resolver CAPTCHAs automaticamente - Integre a API do CapSolver para lidar com desafios de CAPTCHA sem intervenção manual
Manter a flexibilidade - Acesse o poder completo do Selenium quando necessário, mantendo o código simples

2. O que é o Helium?

Helium é uma biblioteca Python que torna o Selenium muito mais fácil de usar. Ele fornece uma API de alto nível que permite escrever automação de navegador em inglês simples.

2.1. Principais Funcionalidades

Sintaxe simples - Escreva click("Enviar") em vez de seletores XPath complexos
Auto-espera - Aguarda automaticamente por elementos para aparecerem
Legível por humanos - O código se parece com instruções: escreva("Olá", em="Pesquisa")
Compatível com Selenium - Acesse o driver do Selenium subjacente quando necessário
Leve - Mínimo overhead sobre o Selenium

2.2. Instalação

bash Copy

# Instalar o Helium
pip install helium

# Instalar a biblioteca requests para a API do CapSolver
pip install requests

2.3. Uso Básico

python Copy

from helium import *

# Iniciar o navegador e navegar
start_chrome("https://wikipedia.org")

# Digitar na caixa de pesquisa
escreva("Programação em Python", em=S("input[name='search']"))

# Clicar no botão de pesquisa
clique(Button("Pesquisar"))

# Verificar se o texto existe
se Texto("Python").existe():
    print("Artigo sobre Python encontrado!")

# Fechar o navegador
kill_browser()

3. O que é o CapSolver?

CapSolver é um serviço de resolução automática de CAPTCHA baseado em IA que suporta uma ampla gama de tipos de CAPTCHA. Ele fornece uma API simples que permite enviar desafios de CAPTCHA e receber soluções em segundos.

3.1. Tipos de CAPTCHA Suportados

Cloudflare Turnstile - O desafio anti-bot mais comum atualmente
reCAPTCHA v2 - Variantes baseadas em imagem e invisíveis
reCAPTCHA v3 - Verificação baseada em pontuação
AWS WAF - CAPTCHA da Amazon Web Services
DataDome - Proteção contra bots para empresas
E muitos mais...

3.2. Começando com o CapSolver

Registre-se em capsolver.com
Adicione fundos à sua conta
Obtenha sua chave de API no painel de controle

Bônus: Use o código HELIUM ao se registrar para receber créditos bônus!

3.3. Pontos de Extremidade da API

Servidor A: https://api.capsolver.com
Servidor B: https://api-stable.capsolver.com

4. Desafios Antes da Integração

Antes de combinar o Helium com o CapSolver, a automação da web enfrentava vários desafios:

Desafio	Impacto
Desafios de CAPTCHA	Resolução manual necessária, interrompendo a automação
Seletores complexos	O Selenium requer seletores XPath/CSS extensos
Problemas de tempo	Elementos não prontos quando acessados
Legibilidade do código	Scripts de automação se tornam difíceis de manter

A integração do Helium + CapSolver resolve esses desafios com código limpo e legível.

5. Métodos de Integração

5.1. Integração da API (Recomendado)

O método de integração da API oferece controle total sobre o processo de resolução de CAPTCHA e funciona com qualquer tipo de CAPTCHA.

5.1.1. Requisitos de Configuração

bash Copy

pip install helium requests

5.1.2. Padrão de Integração Básica

python Copy

import time
import requests
from helium import *

CHAVE_API_CAPSOLVER = "SUA_CHAVE_DE_API"
ENDPOINT_API_CAPSOLVER = "https://api.capsolver.com"


def criar_tarefa(paylod_tarefa: dict) -> str:
    """Cria uma tarefa de resolução de CAPTCHA e retorna o ID da tarefa."""
    resposta = requests.post(
        f"{ENDPOINT_API_CAPSOLVER}/criarTarefa",
        json={
            "chaveCliente": CHAVE_API_CAPSOLVER,
            "tarefa": paylod_tarefa
        }
    )
    resultado = resposta.json()
    if resultado.get("idErro") != 0:
        raise Exception(f"Erro do CapSolver: {resultado.get('descricaoErro')}")
    return resultado["idTarefa"]


def obter_resultado_tarefa(id_tarefa: str, tentativas_maximas: int = 120) -> dict:
    """Verifica o resultado da tarefa até que seja resolvida ou expire o tempo."""
    for _ in range(tentativas_maximas):
        resposta = requests.post(
            f"{ENDPOINT_API_CAPSOLVER}/obterResultadoTarefa",
            json={
                "chaveCliente": CHAVE_API_CAPSOLVER,
                "idTarefa": id_tarefa
            }
        )
        resultado = resposta.json()

        if resultado.get("status") == "pronto":
            return resultado["solução"]
        elif resultado.get("status") == "falha":
            raise Exception(f"Tarefa falhou: {resultado.get('descricaoErro')}")

        time.sleep(1)

    raise TimeoutError("A resolução de CAPTCHA expirou")


def resolver_captcha(paylod_tarefa: dict) -> dict:
    """Fluxo completo de resolução de CAPTCHA."""
    id_tarefa = criar_tarefa(paylod_tarefa)
    return obter_resultado_tarefa(id_tarefa)

5.2. Extensão do Navegador

Você também pode usar a extensão do CapSolver com o Helium para detecção e resolução automática de CAPTCHA.

5.2.1. Etapas de Instalação

Baixe a extensão do CapSolver em capsolver.com/en/extension
Extraia os arquivos da extensão
Configure sua chave de API no arquivo config.js da extensão:

javascript Copy

// No diretório da extensão, edite: assets/config.js
var definido = {
    apiKey: "SUA_CHAVE_DE_API_DO_CAPSOLVER",  // Substitua pela sua chave de API real
    habilitadoParaControleDeListaNegra: false,
    listaUrlNegra: [],
    habilitadoParaReCaptcha: true,
    habilitadoParaReCaptchaV3: true,
    habilitadoParaTurnstile: true,
    // ... outras configurações
}

Carregue-a no Chrome via Helium:

python Copy

from helium import *
from selenium.webdriver import ChromeOptions

options = ChromeOptions()
options.add_argument('--carregar-extensão=/caminho/para/capsolver-extensão')

start_chrome(options=options)
# A extensão detectará e resolverá CAPTCHAs automaticamente

Nota: A extensão deve ter uma chave de API válida configurada antes de poder resolver CAPTCHAs automaticamente.

6. Exemplos de Código

6.1. Resolver reCAPTCHA v2

Este exemplo resolve o reCAPTCHA v2 na página de demonstração do Google com detecção automática da chave do site:

python Copy

import time
import requests
from helium import *
from selenium.webdriver import ChromeOptions

CHAVE_API_CAPSOLVER = "SUA_CHAVE_DE_API"
ENDPOINT_API_CAPSOLVER = "https://api.capsolver.com"


def resolver_recaptcha_v2(chave_site: str, url_pagina: str) -> str:
    """Resolve o reCAPTCHA v2 e retorna o token."""
    # Criar a tarefa
    resposta = requests.post(
        f"{ENDPOINT_API_CAPSOLVER}/criarTarefa",
        json={
            "chaveCliente": CHAVE_API_CAPSOLVER,
            "tarefa": {
                "tipo": "ReCaptchaV2TarefaSemProxy",
                "websiteURL": url_pagina,
                "websiteKey": chave_site,
            }
        }
    )
    resultado = resposta.json()

    if resultado.get("idErro") != 0:
        raise Exception(f"Erro: {resultado.get('descricaoErro')}")

    id_tarefa = resultado["idTarefa"]
    print(f"Tarefa criada: {id_tarefa}")

    # Verificar resultado
    while True:
        resultado = requests.post(
            f"{ENDPOINT_API_CAPSOLVER}/obterResultadoTarefa",
            json={
                "chaveCliente": CHAVE_API_CAPSOLVER,
                "idTarefa": id_tarefa
            }
        ).json()

        if resultado.get("status") == "pronto":
            return resultado["solução"]["gRecaptchaResponse"]
        elif resultado.get("status") == "falha":
            raise Exception(f"Falha: {resultado.get('descricaoErro')}")

        print("  Aguardando solução...")
        time.sleep(1)


def main():
    url_alvo = "https://www.google.com/recaptcha/api2/demo"

    # Configurar o navegador com anti-deteção
    options = ChromeOptions()
    options.add_experimental_option('excludeSwitches', ['enable-automation'])
    options.add_experimental_option('useAutomationExtension', False)
    options.add_argument('--disable-blink-features=AutomationControlled')

    print("Iniciando o navegador...")
    start_chrome(url_alvo, options=options)
    driver = get_driver()

    try:
        time.sleep(2)

        # Detectar automaticamente a chave do site
        elemento_recaptcha = driver.find_element("css selector", ".g-recaptcha")
        chave_site = elemento_recaptcha.get_attribute("data-sitekey")
        print(f"Chave do site detectada: {chave_site}")

        # Resolver o CAPTCHA
        print("\nResolvendo reCAPTCHA v2 com o CapSolver...")
        token = resolver_recaptcha_v2(chave_site, url_alvo)
        print(f"Token obtido: {token[:50]}...")

        # Injetar o token
        print("\nInjetando token...")
        driver.execute_script(f'''
            var campoResposta = document.getElementById('g-recaptcha-response');
            campoResposta.style.display = 'block';
            campoResposta.value = '{token}';
        ''')
        print("Token injetado!")

        # Submeter usando a sintaxe simples do Helium
        print("\nSubmetendo o formulário...")
        clique("Enviar")

        time.sleep(3)

        # Verificar sucesso
        se "Verificação bem-sucedida" em driver.page_source:
            print("\n=== SUCESSO! ===")
            print("reCAPTCHA foi resolvido e o formulário foi submetido!")

    finally:
        kill_browser()


if __name__ == "__main__":
    main()

Teste-o você mesmo:

bash Copy

python demo_recaptcha_v2.py

6.2. Resolver Cloudflare Turnstile

Cloudflare Turnstile é um dos desafios de CAPTCHA mais comuns. Aqui está como resolvê-lo:

python Copy

import time
import requests
from helium import *
from selenium.webdriver import ChromeOptions

CHAVE_API_CAPSOLVER = "SUA_CHAVE_DE_API"
ENDPOINT_API_CAPSOLVER = "https://api.capsolver.com"


def resolver_turnstile(chave_site: str, url_pagina: str) -> str:
    """Resolve Cloudflare Turnstile e retorna o token."""
    resposta = requests.post(
        f"{ENDPOINT_API_CAPSOLVER}/criarTarefa",
        json={
            "chaveCliente": CHAVE_API_CAPSOLVER,
            "tarefa": {
                "tipo": "AntiTurnstileTarefaSemProxy",
                "websiteURL": url_pagina,
                "websiteKey": chave_site,
            }
        }
    )
    resultado = resposta.json()

    if resultado.get("idErro") != 0:
        raise Exception(f"Erro: {resultado.get('descricaoErro')}")

    id_tarefa = resultado["idTarefa"]

    while True:
        resultado = requests.post(
            f"{ENDPOINT_API_CAPSOLVER}/obterResultadoTarefa",
            json={
                "chaveCliente": CHAVE_API_CAPSOLVER,
                "idTarefa": id_tarefa
            }
        ).json()

        if resultado.get("status") == "pronto":
            return resultado["solução"]["token"]
        elif resultado.get("status") == "falha":
            raise Exception(f"Falha: {resultado.get('descricaoErro')}")

        time.sleep(1)


def main():
    url_alvo = "https://seu-site-alvo.com"
    chave_turnstile = "0x4XXXXXXXXXXXXXXXXX"  # Encontre na fonte da página

    # Configurar o navegador
    options = ChromeOptions()
    options.add_argument('--disable-blink-features=AutomationControlled')

    start_chrome(url_alvo, options=options)
    driver = get_driver()

    try:
        # Aguardar o Turnstile carregar
        time.sleep(3)

        # Resolver o CAPTCHA
        print("Resolvendo Turnstile...")
        token = resolver_turnstile(chave_turnstile, url_alvo)
        print(f"Token obtido: {token[:50]}...")

        # Injetar o token
        driver.execute_script(f'''
            document.querySelector('input[name="cf-turnstile-response"]').value = "{token}";

            // Ativar o callback se estiver presente
            const callback = document.querySelector('[data-callback]');
            se (callback) {{
                const nomeCallback = callback.getAttribute('data-callback');
                se (window[nomeCallback]) {{
                    window[nomeCallback]('{token}');
                }}
            }}
        ''')

        # Submeter o formulário usando o Helium
        se Button("Enviar").existe():
            clique("Enviar")

        print("Turnstile contornado!")

    finally:
        kill_browser()


if __name__ == "__main__":
    main()

6.3. Resolver reCAPTCHA v3

O reCAPTCHA v3 é baseado em pontuação e não requer interação do usuário:

python Copy

import time
import requests
from helium import *
from selenium.webdriver import ChromeOptions

CHAVE_API_CAPSOLVER = "SUA_CHAVE_DE_API"
ENDPOINT_API_CAPSOLVER = "https://api.capsolver.com"


def resolver_recaptcha_v3(
    chave_site: str,
    url_pagina: str,
    ação: str = "verificar",
    pontuação_mínima: float = 0.7
) -> str:
    """Resolve o reCAPTCHA v3 com a ação e pontuação mínima especificadas."""
    resposta = requests.post(
        f"{ENDPOINT_API_CAPSOLVER}/criarTarefa",
        json={
            "chaveCliente": CHAVE_API_CAPSOLVER,
            "tarefa": {
                "tipo": "ReCaptchaV3TarefaSemProxy",
                "websiteURL": url_pagina,
                "websiteKey": chave_site,
                "pageAction": ação,
                "minScore": pontuação_mínima
            }
        }
    )
    resultado = resposta.json()

    if resultado.get("idErro") != 0:
        raise Exception(f"Erro: {resultado.get('descricaoErro')}")

    id_tarefa = resultado["idTarefa"]

    while True:
        resultado = requests.post(
            f"{ENDPOINT_API_CAPSOLVER}/obterResultadoTarefa",
            json={
                "chaveCliente": CHAVE_API_CAPSOLVER,
                "idTarefa": id_tarefa
            }
        ).json()

        if resultado.get("status") == "pronto":
            return resultado["solução"]["gRecaptchaResponse"]
        elif resultado.get("status") == "falha":
            raise Exception(f"Falha: {resultado.get('descricaoErro')}")

        time.sleep(1)


def main():
    url_alvo = "https://seu-site-alvo.com"
    chave_recaptcha_v3 = "6LcXXXXXXXXXXXXXXXXXXXXXXXXX"

    # Configurar navegador em modo headless para v3
    options = ChromeOptions()
    options.add_argument('--headless')

    start_chrome(url_alvo, options=options)
    driver = get_driver()

    try:
        # Resolver reCAPTCHA v3 com ação "login"
        print("Resolvendo reCAPTCHA v3...")
        token = resolver_recaptcha_v3(
            chave_recaptcha_v3,
            url_alvo,
            ação="login",
            pontuação_mínima=0.9
        )

        # Injetar o token
        driver.execute_script(f'''
            var campoResposta = document.querySelector('[name="g-recaptcha-response"]');
            se (campoResposta) {{
responseField.value = '{token}';
            }}
            // Chamar o callback se existir
            if (typeof onRecaptchaSuccess === 'function') {{
                onRecaptchaSuccess('{token}');
            }}
        ''')

        print("reCAPTCHA v3 contornado!")

    finally:
        kill_browser()


if __name__ == "__main__":
    main()

7. Boas Práticas

7.1. Configuração do Navegador

Configure o Chrome para parecer mais como um navegador regular:

python Copy

from helium import *
from selenium.webdriver import ChromeOptions

options = ChromeOptions()
options.add_experimental_option('excludeSwitches', ['enable-automation'])
options.add_experimental_option('useAutomationExtension', False)
options.add_argument('--disable-blink-features=AutomationControlled')
options.add_argument('--window-size=1920,1080')

start_chrome(options=options)

7.2. Combinando Helium com Selenium

Use a sintaxe simples do Helium para a maioria das operações, mas acesse o Selenium quando necessário:

python Copy

from helium import *

start_chrome("https://site-alvo.com")

# Use o Helium para interações simples
escrever("username", em="Email")
escrever("password", em="Senha")

# Acesse o driver do Selenium para operações complexas
driver = get_driver()
driver.execute_script("window.scrollTo(0, document.body.scrollHeight)")

# Volte ao Helium
clicar("Login")

7.3. Limitação de Taxa

Evite disparar limitações de taxa adicionando atrasos aleatórios:

python Copy

import random
import time

def atraso_humano(min_sec=1.0, max_sec=3.0):
    """Atraso aleatório para imitar comportamento humano."""
    time.sleep(random.uniform(min_sec, max_sec))

# Use entre ações
clicar("Próximo")
atraso_humano()
escrever("dados", em="Entrada")

7.4. Tratamento de Erros

Sempre implemente tratamento de erros adequado para resolução de CAPTCHA:

python Copy

def resolver_com_retentativa(payload_da_tarefa: dict, max_tentativas: int = 3) -> dict:
    """Resolver CAPTCHA com lógica de tentativa de novo."""
    for tentativa in range(max_tentativas):
        try:
            return resolver_captcha(payload_da_tarefa)
        except TimeoutError:
            if tentativa < max_tentativas - 1:
                print(f"Tempo esgotado, tentando novamente... ({tentativa + 1}/{max_tentativas})")
                time.sleep(5)
            else:
                raise
        except Exception as e:
            if "saldo" in str(e).lower():
                raise  # Não tentar novamente erros de saldo
            if tentativa < max_tentativas - 1:
                time.sleep(2)
            else:
                raise

7.5. Modo Headless

Use o modo headless para automação em segundo plano:

python Copy

from helium import *
from selenium.webdriver import ChromeOptions

options = ChromeOptions()
options.add_argument('--headless')
options.add_argument('--disable-gpu')

start_chrome("https://site-alvo.com", options=options)

8. Helium vs Selenium: Comparação Rápida

Operação	Selenium	Helium
Clicar no botão	`driver.find_element(By.XPATH, "//button[text()='Enviar']").click()`	`clicar("Enviar")`
Digitar texto	`driver.find_element(By.NAME, "email").send_keys("test@test.com")`	`escrever("test@test.com", em="Email")`
Pressionar Enter	`element.send_keys(Keys.ENTER)`	`pressionar(ENTER)`
Verificar se o texto existe	`"Bem-vindo" in driver.page_source`	`Texto("Bem-vindo").existe()`

9. Conclusão

A integração do Helium e do CapSolver cria uma ferramenta elegante para automação web:

Helium fornece uma API limpa e legível para automação de navegadores
CapSolver resolve CAPTCHAs com resolução baseada em IA
Juntos permitem automação sem problemas com código mínimo

Seja para construir raspadores de web, sistemas de testes automatizados ou pipelines de coleta de dados, essa combinação oferece simplicidade e poder.

Bônus: Use o código HELIUM ao se cadastrar no CapSolver para receber créditos bônus!

10. Perguntas Frequentes

10.1. Por que escolher o Helium em vez do Selenium puro?

O Helium torna o Selenium mais fácil de usar:

Sintaxe muito mais simples e legível para humanos
Espera automática por elementos
Código menos verboso
Acesso completo ao Selenium quando necessário
Tempo de desenvolvimento mais rápido

10.2. Quais tipos de CAPTCHA funcionam melhor com essa integração?

O CapSolver suporta todos os principais tipos de CAPTCHA. O Turnstile do Cloudflare e o reCAPTCHA v2/v3 têm as maiores taxas de sucesso. A integração funciona perfeitamente com qualquer CAPTCHA que o CapSolver suporte.

10.3. Posso usar isso no modo headless?

Sim! O Helium suporta modo headless via ChromeOptions. No modo headless, o reCAPTCHA v3 e CAPTCHAs baseados em token funcionam perfeitamente. Para CAPTCHAs visíveis v2, o modo com interface pode oferecer melhores resultados.

10.4. Como encontrar a chave do site para um CAPTCHA?

Procure no código-fonte da página por:

Turnstile: atributo data-sitekey ou elementos cf-turnstile
reCAPTCHA: atributo data-sitekey no div g-recaptcha

10.5. O que fazer se a resolução do CAPTCHA falhar?

Soluções comuns:

Verifique sua chave de API e saldo
Certifique-se de que a chave do site esteja correta
Confirme que a URL da página corresponda à onde o CAPTCHA aparece
Para v3, tente ajustar o parâmetro de ação e a pontuação mínima
Implemente lógica de tentativa de novo com atrasos

10.6. Posso ainda usar recursos do Selenium com o Helium?

Sim! Chame get_driver() para acessar o WebDriver do Selenium subjacente para qualquer operação que o Helium não cubra diretamente.

Ver mais

web scrapingApr 22, 2026

Arquitetura de Web Scraping em Rust para Extração de Dados Escalável

Aprenda arquitetura de raspagem web escalável em Rust com reqwest, scraper, raspagem assíncrona, raspagem de navegador headless, rotação de proxies e tratamento de CAPTCHA compatível.

Adélia Cruz

web scrapingApr 08, 2026

Selenium vs Puppeteer para Resolução de CAPTCHA: Comparação de Desempenho e Caso de Uso

Compare o Selenium vs Puppeteer para resolver CAPTCHA. Descubra benchmarks de desempenho, notas de estabilidade e como integrar o CapSolver para o máximo de sucesso.